%%::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
%%
%%    This file is part of ICTP RegCM.
%%    
%%    Use of this source code is governed by an MIT-style license that can
%%    be found in the LICENSE file or at
%%
%%         https://opensource.org/licenses/MIT.
%%
%%    ICTP RegCM is distributed in the hope that it will be useful,
%%    but WITHOUT ANY WARRANTY; without even the implied warranty of
%%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
%%
%%::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

We will in this chapter go through a sample session in using the model with
a sample configuration file prepared for this task.

\section{Setting up the run environment}

The model executables prepared in chapter \ref{install} are waiting for us to
use them. So let's give them a chance.

The model test run proposed here requires around 100Mb of disk space to store
the DOMAIN and ICBC in input and the output files. We will assume here that you,
the user, have already established a convenient directory on a disk partition
with enough space identified in the following discussion with \verb=$REGCM_RUN=

We will setup in this directory a standard environment where the model can be
executed for the purpose of learning how to use it.

We assume here the model has been compiled using the \verb=CLM45= option (i.e.
the \verb=--enable-clm45= has been added to the configure script).

\begin{Verbatim}
$> cd $REGCM_RUN
$> mkdir input output
$> ln -sf $REGCM_ROOT/bin .
$> cp $REGCM_ROOT/Testing/test_001.in .
$> cd $REGCM_RUN
\end{Verbatim}

Now we are ready to modify the input namelist file to reflect this directory
layout. A namelist file in FORTRAN is a convenient way to give input to a
program in a formatted file, read at runtime by the program to setup its
execution behaviour. So the next step is somewhat tricky, as you need to edit
the namelist file respecting its well defined syntax. Open your preferred text
file editor and load the \verb=test_001.in= file. You will need to modify for
the scope of the present tutorial the following lines:

\begin{Verbatim}
FROM:
 dirter = '/set/this/to/where/your/domain/file/is',
TO:
 dirter = 'input/',
\end{Verbatim}

\begin{Verbatim}
FROM:
 inpter = '/set/this/to/where/your/surface/dataset/is',
TO:
 inpter = 'REGCM_GLOBEDAT',
\end{Verbatim}

where \verb=REGCM_GLOBEDAT= is the directory where input data have been
downloaded in chapter \ref{obdata}.

\begin{Verbatim}
FROM:
 dirglob = '/set/this/to/where/your/icbc/for/model/is',
TO:
 dirglob = 'input/',
\end{Verbatim}

\begin{Verbatim}
FROM:
 inpglob = '/set/this/to/where/your/input/global/data/is',
TO:
 inpglob = 'REGCM_GLOBEDAT',
\end{Verbatim}

and last bits:

\begin{Verbatim}
FROM:
 dirout='/set/this/to/where/your/output/files/will/be/written'
TO:
 dirout='output/'
\end{Verbatim}

These modifications just reflect the above directory layout proposed for this
tutorial, and any of these paths can point anywhere on your system disks.
The path is limited to $256$ characters.
We are now ready to execute the first program of the RegCM model.

\section{Create the DOMAIN file using terrain}

The first step is to create the DOMAIN file to localize the model on a world
region.
The program which does this for you reading the global databases is
\verb=terrain= .

To launch the terrain program, enter the following commands:

\begin{Verbatim}
$> cd $REGCM_RUN
$> ./bin/terrainCLM45 test_001.in
\end{Verbatim}

If everything is correctly configured up to this point, the model should print
something on stdout, and the last lines will be:

\begin{Verbatim}
 Grid data written to output file                                               
 Successfully completed terrain fields generation
\end{Verbatim}

In the input directory the program will write the following two files:

\begin{Verbatim}
$> ls input
test_001_DOMAIN000.nc test_001_LANDUSE
\end{Verbatim}

The DOMAIN file contains the localized topography and landuse databases, as
well as projection information and land sea mask. The second file is an ASCII
encoded version of the landuse, used for modifying it on request. We will cover
it's usage later on.  To have a quick look at the DOMAIN file content, you may
want to use the ncview program:

\begin{Verbatim}
$> ncview input/test_001_DOMAIN000.nc
\end{Verbatim}

\section{Create the CLM45 input data}

For the CLM4.5 model, additional global surface data must be interpolated on
the model grid. To do this, the user must run the \verb=mksurfdata= program:

\begin{Verbatim}
$> cd $REGCM_RUN
$> ./bin/mksurfdataCLM45 test_001.in
\end{Verbatim}

This creates the file:

\begin{Verbatim}
input/test_001_CLM45_surface.nc
\end{Verbatim}

\section{Create the SST using the sst program}

We are now ready to create the Sea Surface Temperature for the model, reading
a global dataset.
The program which does this for you is the \verb=sst= program, which is
executed with the following commands:

\begin{Verbatim}
$> cd $REGCM_RUN
$> ./bin/sstCLM45 test_001.in
\end{Verbatim}

If everything is correctly configured up to this point, the model should print
something on stdout, and the last line will be:

\begin{Verbatim}
 Successfully generated SST
\end{Verbatim}

The input directory now contains a new file:

\begin{Verbatim}
$> ls input
test_001_CLM45_surface.nc  test_001_DOMAIN000.nc
test_001_LANDUSE           test_001_SST.nc
\end{Verbatim}

The SST file contains the Sea Surface temperature to be used in generating the
Initial and Boundary Conditions for the model for the period specified in the
namelist file. Again you may want to use the ncview program to look at
file content:

\begin{Verbatim}
$> ncview input/test_001_SST.nc
\end{Verbatim}

this will allow you to view the interpolated sst field on the X11 window.

\section{Create the ICBC files using the icbc program}

Next step is to create the ICBC (Initial Condition, Boundary Conditions) for
the model itself. The program which does this for you is the \verb=icbc=
program, executed with the following commands:

\begin{Verbatim}
$> cd $REGCM_RUN
$> ./bin/icbcCLM45 test_001.in
\end{Verbatim}

If everything is correctly configured up to this point, the model should print
something on stdout, and the last line will be:

\begin{Verbatim}
 Successfully completed ICBC
\end{Verbatim}

The input directory now contains two more files:

\begin{Verbatim}
$> ls -1 input
test_001_CLM45_surface.nc
test_001_DOMAIN000.nc
test_001_ICBC.2020060100.nc
test_001_ICBC.2020070100.nc
test_001_LANDUSE
test_001_SST.nc
\end{Verbatim}

The ICBC files contain the surface pressure, surface temperature, horizontal
3D wind components, 3D temperature and mixing ratio for the RegCM domain for the
period and time resolution specified in the input file.
Again you may want to use the ncview program to look at file content:

\begin{Verbatim}
$> ncview input/test_001_ICBC.2020060100.nc
\end{Verbatim}

We are now ready to run the model!

\section{First RegCM model simulation}

The model has now all needed data to allow you to launch a test simulation,
the final goal of our little tutorial. By using command line tools for the
MPI library, \verb=mpirun=, we can run in parallel the model using all the
available CPU computing cores of the system:

\begin{Verbatim}
$> cd $REGCM_RUN
$> mpirun ./bin/regcmMPICLM45 test_001.in
\end{Verbatim}

Now the model will start running, and a series of diagnostic messages will be
printed on screen. As this is a simulation known to behave well, no stoppers
will appear, so you may want now to have a coffee break and come back in 10
minutes from now.

At the end of the run, the model will print the following message:

\begin{Verbatim}
 RegCM V4 simulation successfully reached end
\end{Verbatim}

The output directory now contains four files:

\begin{Verbatim}
$> ls output
test_001_ATM.2020060100.nc test_001_SRF.2020060100.nc
test_001_RAD.2020060100.nc test_001_SAV.2020070100.nc
\end{Verbatim}

along with some \verb=.clm.= files from the CLM45 model.
The ATM file contains the atmosphere status from the model, the SRF file
contains the surface diagnostic variables, and the RAD file contains radiation
fluxes information. The SAV file stores the status of the model at the end of
the simulation period to enable a restart, thus allowing a long simulation
period to be splitted in shorter simulations.

To have a look for example at surface fields, you may want to use the
following command:

\begin{Verbatim}
$> ncview output/test_001_SRF.2020060100.nc
\end{Verbatim}

This is the end of this little tutorial, and in the next chapter we will
examine how to configure the model for your research needs.
